home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / NDK / NDK_3.5 / Documentation / Autodocs / picture_dtc.doc < prev    next >
Encoding:
Text File  |  1999-10-22  |  11.5 KB  |  323 lines
  1. TABLE OF CONTENTS
  2.  
  3. picture.datatype/picture.datatype
  4. picture.datatype/picture.datatype           picture.datatype/picture.datatype
  5.  
  6.    NAME
  7.     picture.datatype -- the root data type for pictures.
  8.  
  9.    FUNCTION
  10.     The picture.datatype is the super-class for any picture related
  11.     classes.
  12.  
  13.    METHODS
  14.     OM_NEW -- Create a new picture object.
  15.  
  16.     OM_GET -- Obtain the value of an attribute.
  17.  
  18.     OM_SET -- Set the values of multiple attributes.
  19.  
  20.     OM_UPDATE -- Update the values of multiple attributes.
  21.  
  22.     OM_DISPOSE -- Dispose of a picture object.
  23.  
  24.     GM_LAYOUT -- Layout the object and notify the application of the
  25.         title and size.
  26.  
  27.     GM_HITTEST -- Determine if the object has been hit with the
  28.         mouse.
  29.  
  30.     GM_GOACTIVE -- Tell the object to go active.
  31.  
  32.     GM_HANDLEINPUT -- Handle input.
  33.  
  34.     GM_RENDER -- Cause the graphic to render.
  35.  
  36.     DTM_PROCLAYOUT -- Layout (remap) the picture on the application's
  37.         process.
  38.  
  39.     DTM_FRAMEBOX -- Obtain the display environment that the picture
  40.         requires.
  41.  
  42.     DTM_SELECT -- Select an area in the picture.
  43.  
  44.     DTM_CLEARSELECTED -- Deselect the selected area of the picture.
  45.  
  46.     DTM_COPY -- Copy the selected area of the picture to the clipboard
  47.         as an ILBM.  If no area is selected, then the entire picture
  48.         is copied.
  49.  
  50.     DTM_PRINT -- Print the selected area of the picture.  If no area
  51.         is selected, then the entire picture is printed.
  52.  
  53.     DTM_WRITE -- Write the selected area of the picture to a file as an
  54.         ILBM.  If no area is selected, then the entire picture is
  55.         saved.
  56.  
  57.     PDTM_WRITEPIXELARRAY -- Transfer pixel data to the picture
  58.         object. Requires that PDTA_SourceMode==PMODE_V43, as
  59.         described below. (V43)
  60.  
  61.     PDTM_READPIXELARRAY -- Transfer pixel data from the picture
  62.         object. Requires that PDTA_DestMode==PMODE_V43, as
  63.         described below. (V43)
  64.  
  65.    TAGS
  66.     OBP_Precision (ULONG) -- Precision to use when obtaining colors.
  67.         See the PRECISION_[..] defines in <graphics/view.h>.
  68.         Applicability is (I). Defaults to PRECISION_IMAGE.
  69.  
  70.     PDTA_ModeID (ULONG) -- Set and get the graphic mode id of the
  71.         picture (see <graphics/modeid.h>).
  72.  
  73.         Applicability is (ISG).
  74.  
  75.     PDTA_BitMapHeader (struct BitMapHeader *) -- Get the
  76.         base information for the picture.  BitMapHeader is defined in
  77.         <datatypes/pictureclass.h>
  78.  
  79.         Applicability is (G).
  80.  
  81.     PDTA_BitMap (struct BitMap *) -- Pointer to a class-allocated
  82.         bitmap, that will end up being freed by the picture class in the
  83.         OM_DISPOSE method.
  84.  
  85.         Applicability is (ISG).
  86.  
  87.     PDTA_ColorRegisters (struct ColorRegister *) -- Color table; its
  88.         contents should match the colours in the PDTA_CRegs table.
  89.  
  90.         Applicability is (G).
  91.  
  92.     PDTA_CRegs (ULONG *) -- Color table to use with SetRGB32CM().
  93.  
  94.         Applicability is (G).
  95.  
  96.     PDTA_GRegs (ULONG *) -- Color table; this table is initialized
  97.         during the layout process and will contain the colours the
  98.         picture will use after remapping. If no remapping takes
  99.         place, these colours will match those in the PDTA_CRegs table.
  100.  
  101.         Applicability is (G).
  102.  
  103.     PDTA_ColorTable (UBYTE *) -- Shared pen table; this table is
  104.         initialized during the layout process while the picture
  105.         is being remapped.
  106.  
  107.         Applicability is (G).
  108.  
  109.     PDTA_ColorTable2 (UBYTE *) -- Shared pen table; in most places
  110.         this table will be identical to the PDTA_ColorTable table.
  111.         Some of the colours in this table might match the original
  112.         colour palette a little better than the colours picked for
  113.         the other table. The picture.datatype uses the two tables
  114.         during remapping, alternating for each pixel.
  115.  
  116.         Applicability is (G).
  117.  
  118.     PDTA_Allocated (ULONG) -- OBSOLETE; DO NOT USE
  119.  
  120.     PDTA_NumColors (UWORD) -- Number of colors used by the picture.
  121.  
  122.         Applicability is (ISG).
  123.  
  124.     PDTA_NumAlloc (UWORD) -- Number of colors allocated by the picture.
  125.         In this context `allocated' refers to colours allocated via
  126.         graphics.library/ObtainBestPenA.
  127.         Applicability is (G).
  128.  
  129.     PDTA_Remap (BOOL) -- Indicate whether the picture should be
  130.         remapped or not.
  131.  
  132.         Applicability is (I). Defaults to TRUE.
  133.  
  134.     PDTA_Screen (struct Screen *) -- Pointer to the screen to remap
  135.         the picture to.  Only used if the object is not going to be
  136.         added to a window.
  137.  
  138.         Applicability is (IS). Defaults to NULL.
  139.  
  140.     PDTA_FreeSourceBitMap (BOOL) -- Indicate whether the source
  141.         bitmap should be freed immediately by the picture.datatype
  142.         after the GM_LAYOUT method is called.
  143.  
  144.         Applicability is (IS). Defaults to FALSE.
  145.  
  146.     PDTA_Grab (Point *) -- Pointer to a Point structure, that
  147.         defines the grab point of the picture.
  148.  
  149.         Applicability is (ISG).
  150.  
  151.     PDTA_DestBitMap (struct BitMap *) -- Pointer to the remapped
  152.         bitmap.
  153.  
  154.         Applicability is (G).
  155.  
  156.     PDTA_ClassBitMap (struct BitMap *) -- Pointer to the BitMap
  157.         allocated by the subclass (e.g. ilbm.datatype) which read
  158.         the picture. picture.datatype will never free this bitmap,
  159.         the subclass is responsible for doing this.
  160.  
  161.         Applicability is (ISG).
  162.  
  163.     PDTA_NumSparse (UWORD) -- Number of entries in the sparse color
  164.         table.
  165.  
  166.         Applicability is (I). Defaults to 0.
  167.  
  168.     PDTA_SparseTable (UBYTE *) -- Pointer to a table of pen numbers
  169.         indicating which colors should be used when remapping the
  170.         picture.  This array must contain as many entries as indicated
  171.         by the PDTA_NumSparse tag.
  172.  
  173.         Applicability is (I). Defaults to NULL.
  174.  
  175.     PDTA_SourceMode (LONG) -- Used by subclass implementors only; this
  176.         tag determines whether the picture.datatype expects a bitmap
  177.         as the input parameter (PMODE_V42) or accepts PDTM_WRITEPIXELARRAY
  178.         messages instead (PMODE_V43).
  179.  
  180.         Applicability is (ISG). Defaults to PMODE_V42. (V43)
  181.  
  182.     PDTA_DestMode (LONG) -- Used by application software writers only;
  183.         this tag determines whether the picture.datatype will return
  184.         only standard format BitMaps (PMODE_V42) or whether it will
  185.         return BitMaps about whose memory layout the caller should
  186.         not speculate (PMODE_V43). If set to PMODE_V43, you must not
  187.         examine the contents of the BitMap you receive from
  188.         picture.datatype.
  189.  
  190.         Applicability is (ISG). Defaults to PMODE_V43. (V43)
  191.  
  192.     PDTA_UseFriendBitMap (BOOL) -- If set to TRUE, all BitMap
  193.         allocations done by picture.datatype will be done with
  194.         a friend BitMap as a reference (see graphics.library/AllocBitMap).
  195.  
  196.         Applicability is (ISG). Defaults to TRUE. (V43)
  197.  
  198.     PDTA_MaskPlane (PLANEPTR) -- Pointer to a bit plane suitable
  199.         for use with BltMaskBitMapRastPort(), or NULL if the
  200.         picture has no transparent colours.
  201.  
  202.         Applicability is (G). Defaults to NULL. (V43)
  203.  
  204.     PDTA_WhichPicture (ULONG) -- Index number of the picture to load.
  205.         For several pictures to be stored in the same file, index
  206.         number 0 would refer to the first picture, index number 1 would
  207.         refer to the second picture, etc. This tag works together with
  208.         the PDTA_GetNumPictures tag. To load a specific picture from
  209.         a file, first check how many pictures there are. This is done
  210.         by asking the picture.datatype subclass to load the first
  211.         picture and also to count the number of pictures, like this:
  212.  
  213.             Object * picture;
  214.             ULONG numPictures;
  215.  
  216.             /* Note: you must always initialize this value
  217.              *       prior to querying the number of pictures
  218.              *       stored in a file.
  219.              */
  220.             numPictures = PDTANUMPICTURES_Unknown;
  221.             picture = NewDTObject(...,
  222.                           PDTA_WhichPicture,0,
  223.                           PDTA_GetNumPictures,&numPictures,
  224.                           ...
  225.                       TAG_DONE);
  226.  
  227.             /* Now check if there is more than a single picture
  228.              * in this file.
  229.              */
  230.             if(numPictures != PDTANUMPICTURES_Unknown &&
  231.                numPictures > 1)
  232.             {
  233.                 Object * secondPicture;
  234.  
  235.                 picture = NewDTObject(...,
  236.                               PDTA_WhichPicture,1,
  237.                               ...
  238.                           TAG_DONE);
  239.  
  240.                 ...
  241.             }
  242.  
  243.         Older picture.datatype subclasses may not support the
  244.         PDTA_WhichPicture and PDTA_GetNumPictures tags. The only way
  245.         to find out is by using the query tag PDTA_GetNumPictures.
  246.         If the subclass supports both the PDTA_GetNumPictures and
  247.         PDTA_WhichPicture tags, it will modify the value stored in
  248.         the variable passed with PDTA_GetNumPictures.
  249.  
  250.         If the requested picture is unavailable (e.g. you might ask
  251.         for picture #10, whereas there are only three pictures in a
  252.         file) the subclass will return NULL and set the error
  253.         code DTERROR_NOT_AVAILABLE. This does not signify that the file
  254.         in question was not found, it just tells you that the picture
  255.         with the requested index number is not available.
  256.  
  257.         Note that for older picture.datatype subclasses, the
  258.         PDTA_WhichPicture tag will be ignored. No matter which value
  259.         you supply, you will always receive the first picture stored
  260.         in the file.
  261.  
  262.         Applicability is (I). Defaults to 0. (V44)
  263.  
  264.     PDTA_GetNumPictures (ULONG *) -- Query the number of pictures
  265.         stored in a file. For an example of its use, see the description
  266.         for the PDTA_WhichPicture tag.
  267.  
  268.         Note that older picture.datatype subclasses will ignore this
  269.         tag. Consequently, the variable you pass in may not be modified.
  270.         Therefore you should initialize it to the constant value
  271.         PDTANUMPICTURES_Unknown before you pass it to NewDTObject().
  272.  
  273.         This tag is unusual in that it does not operate on an already
  274.         existing object in the GetDTAttrs() context. This was done for
  275.         practical reasons, i.e. while the picture.datatype subclass is
  276.         still processing the image data it may be much more convenient
  277.         to count the number of pictures in a file than it would be later
  278.         when the file has already been read.
  279.  
  280.         Applicability is (I). Defaults to NULL. (V44)
  281.  
  282.     PDTA_MaxDitherPens (ULONG) -- Maximum number of pens to use during
  283.         colour quantization.
  284.  
  285.         Applicability is (ISG). Defaults to 125. (V44)
  286.  
  287.     PDTA_DitherQuality (ULONG) -- Quality of the dithering algorithm to
  288.         be used during colour quantization. A value of 0 yields no or
  289.         only little picture quality improvement while a value of 2 will
  290.         yield noticeably better picture quality. Generally, the higher
  291.         the quality you demand, the better the output will look like.
  292.  
  293.         Applicability is (ISG). Defaults to 1. (V44)
  294.  
  295.     PDTA_AllocatedPens (UBYTE *) -- Get the pointer to the table of
  296.         allocated pens. Each entry stands for the pen assigned to the
  297.         colour of the corresponding palette entry. Please note that
  298.         you may receive NULL as a return value instead of a pointer
  299.         and that the table may not hold any valid information unless
  300.         the value returned with the PDTA_NumAlloc tag is greater
  301.         than zero.
  302.  
  303.         Applicability is (G). (V44)
  304.  
  305.    NOTES
  306.     The PDTA_Allocated tag should not be used since it was never
  307.     implemented in any way the documentation suggested.
  308.  
  309.     picture.datatype V44 no longer suffers from the layout restrictions
  310.     present in older picture.datatype revisions. This means for example,
  311.     that for an extra-halfbrite picture you need no longer open a
  312.     custom screen to display it. Any screen will do. The same holds
  313.     true for hold-and-modify pictures.
  314.  
  315.     Writing greyscale data to a picture (via the PBPAFMT_GREY8 pixel
  316.     format and the PDTM_WRITEPIXELARRAY method) automatically
  317.     configures the picture colour palette when the first line is
  318.     written. The palette is reset to 256 shades of grey with 0 = black
  319.     and 255 = white. If you do not want this to happen, do not use the
  320.     PBPAFMT_GREY8 pixel format: use PBPAFMT_LUT8 instead. This will
  321.     give you complete control over the picture's colour palette.
  322.  
  323.